Advice Manager

The battle advice manager provides a framework for managing the delivery of general advice by the advisor in battle. Client scripts create advice_monitor objects for each item of advice they may wish to deliver. Each advice monitor is then set up to listen for certain in-game events or conditions becoming true, at which point the advice may be triggered. Advice monitors are also assigned a priority to allow higher-priority advice to supercede lower-priority advice.

Advice monitors create and use an advice_manager object to help manage the process of advice delivery. Client scripts do not need to create the advice_manager themselves, but by doing so they will be able to set it into debug mode for more output with advice_manager:set_debug, or disable advice with advice_manager:set_advice_enabled.

The advice manager triggers the ScriptEventDeploymentPhaseBegins when deployment phase begins. Advice monitors should listen for this if they want to trigger during deployment rather than another event.

The battle advice system outputs debug information to the Lua - Interventions tab on the console.

Loaded in Battle loaded in battle
Back to top

Creation

advice_manager:new([boolean debug mode])
Creates and returns a new advice manager. Client scripts do not need to call this, however by doing so they will be able to set it into debug mode for more output with advice_manager:set_debug, or disable advice with advice_manager:set_advice_enabled.

Parameters:

1

boolean

optional, default value=false

debug mode

Returns:

  1. advice_manager advice manager

Example:

-- create an advice manager with debug output
am = advice_manager:new(true);

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

advice_manager:set_debug([boolean debug mode])
Sets debug mode on the advice manager for more output

Parameters:

1

boolean

optional, default value=true

debug mode

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_advice.lua, line 147

advice_manager:set_advice_enabled([boolean enable advice])

Allows client scripts to enable or disable advice triggered by the advice manager system.

Parameters:

1

boolean

optional, default value=true

enable advice

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_advice.lua, line 159

Advice Monitor

Advice monitors provide a mechanism for the detection of trigger conditions of an individual item of advice, and for deciding whether to then trigger it. One advice monitor encapsulates the triggering conditions for one line of generic advice, so it's common to create multiple such objects. Each advice monitor attempts to create an advice_manager (should one not exist already) which provides backbone services to all running advice monitors.

Advice monitor trigger conditions may be specified as an event, a event with a condition, or just a condition. In the latter case the condition is repeatedly polled until it becomes true. Advice monitors also support the declaration of start conditions, which define when an advice monitor should start listening/polling for the trigger conditions, and halt conditions, which define when the monitor should stop. Like trigger conditions, start conditions and halt conditions may be specified as events, events with conditions, or just conditions. Multiple start/trigger/halt conditions may be specified for each advice monitor.

Advice monitors also support the calling of a trigger function as well as, or instead of, playing the advice itself. Use advice_monitor:set_trigger_callback to set such a function.

Should the advice associated with the advice monitor have been played before, the advice monitor shuts down on startup.

Back to top

Creation

advice_monitor:new(string name, number priority, string advice key, [table infotext])
Creates and returns a new advice monitor.

Parameters:

1

string

Name for the advice monitor. Must be unique amongst advice monitors.

2

number

Priority of the advice. When two items of advice wish to trigger at the same time, the advice with the higher priority is triggered.

3

string

Key of the advice to trigger. The history of this advice thread is also checked when monitor is started - if it has been heard before then the monitor does not start.

4

table

optional, default value=nil

Table of infotext keys to show alongside the advice.

Returns:

  1. advice_monitor advice monitor

Example - Deployment advice:

advice_deployment = advice_monitor:new(
    "deployment",
    50,
    "war.battle.advice.deployment.001",
    {
        "war.battle.advice.deployment.info_001",
        "war.battle.advice.deployment.info_002",
        "war.battle.advice.deployment.info_003",
        "war.battle.advice.deployment.info_004"
    }
);

defined in ../working_data/script/_lib/lib_battle_advice.lua, line 561

Back to top

Configuration

advice_monitor:set_advice_level(number advice level)
Sets the minimum advice level at which the advice may be allowed to trigger. If the advice level is set to less than that required by the advice monitor when the advice monitor is started, then the monitor will immediately terminate. By default, advice monitors allow their advice to trigger if the advice level is set to low or high.

Parameters:

1

number

Minimum advice level. Valid values are 0 (minimul advice), 1 (low advice) and 2 (high advice).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_advice.lua, line 654

advice_monitor:set_can_interrupt_other_advice([boolean can interrupt])
Sets whether this advice can interrupt other advice. By default this is disabled.

Parameters:

1

boolean

optional, default value=true

can interrupt

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_advice.lua, line 666

advice_monitor:set_delay_before_triggering(number delay in ms)
Sets a delay period before the advice is actually triggered. This is 1000ms by default.

Parameters:

1

number

delay in ms

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_advice.lua, line 678

advice_monitor:set_trigger_callback(function callback, [boolean dont trigger advice])
Sets a callback for the advice monitor to call at the point the advice is triggered (i.e. after any delay set with advice_monitor:set_delay_before_triggering).

Parameters:

1

function

Callback to call.

2

boolean

optional, default value=false

If set to true, this monitor will trigger the callback but will not trigger the supplied advice or infotext itself. Set this to true if the callback takes care of triggering the advice itself.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_advice.lua, line 688

advice_monitor:set_halt_callback(function callback)
Sets a callback for the advice monitor to call at the point the advice is halted.

Parameters:

1

function

Callback to call.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_advice.lua, line 702

advice_monitor:set_halt_advice_on_battle_end([boolean halt on end])
Sets the advice monitor to automatically halt or not when the battle ends. Advice monitors do halt when the battle ends by default - use this function to suppress this behaviour.

Parameters:

1

boolean

optional, default value=true

halt on end

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_advice.lua, line 715

Back to top

Start Conditions

By default, advice monitors start monitoring for their trigger conditions when the deployment phase of the battle begins. This can be changed by adding one or more start conditions with advice_monitor:add_start_condition.

advice_monitor:add_start_condition(function condition, [string event])
Adds a start condition for the advice monitor, which determines when the advice monitor will begin monitoring its trigger conditions. Supply one of the following combination of arguments:
  • A condition function that returns a boolean value. In this case, the condition will be repeatedly called until it returns true. Once this happens the advice monitor will begin monitoring for the trigger condition.

  • A condition function that returns a boolean value, and an event. In this case, the event will be listened for and, when received, the condition function called. Should it return true the advice monitor will begin monitoring for the trigger condition.

  • true in place of a condition function, and an event. In this case, the advice monitor will begin monitoring for the trigger condition as soon as the event is received, with no conditional check.

Parameters:

1

function

Conditional function. Supply a function that returns a boolean value, or true (if also supplying an event).

2

string

optional, default value=nil

Event to test.

Returns:

  1. nil

Example:

This advice monitor starts monitoring its trigger conditions when a player unit routs.
advice_player_rallies:add_start_condition(
    function()
        return num_units_routing(player_army) > 0
    end
);

Example:

This advice monitor starts monitoring its trigger conditions when a unit attacks the walls.
advice_siege_capture:add_start_condition(
    true,
    "BattleUnitAttacksWalls"
);

Example:

This advice monitor starts at the beginning of conflict phase, if the player has one or more artillery pieces.
advice_player_artillery:add_start_condition(
    function()    
        local player_artillery = num_units_passing_test(
            bm:get_player_army(),
            function(unit)
                return unit:unit_class() == "art_fld";
            end
        );
        return player_artillery > 0;
    end,
    "ScriptEventConflictPhaseBegins"
);

defined in ../working_data/script/_lib/lib_battle_advice.lua, line 742

Back to top

Trigger Conditions

Trigger conditions tell advice monitors when to try and play advice. Once started (either when deployment phase begins or when a condition registered with advice_monitor:add_start_condition passes), an advice monitor begins monitoring for one of its trigger conditions to pass. Once a trigger condition passes the advice monitor stops its trigger monitors, and sends the advice to the advice_manager. This waits a short period for other advice to also trigger, then picks the highest-priority advice from the available selection. The unsuccessful advice monitors are restarted when the successful advice finishes, and may be triggered again.

Each advice monitor must have at least one trigger condition registered, otherwise it won't be able to fire its advice at all.

advice_monitor:add_trigger_condition(function condition, [string event])
Adds a trigger condition for the advice monitor. Supply one of the following combination of arguments:
  • A condition function that returns a boolean value. In this case, the condition will be polled until it passes, at which point the advice will be considered for playing.

  • A condition function that returns a boolean value, and an event. In this case, the event will be listened for and, when received, the condition checked. Should it pass, the advice will be considered for playing.

  • true in place of a condition function, and an event. In this case, the advice will be considered for playback when the event is received.

Parameters:

1

function

Conditional function. Supply a function that returns a boolean value, or true (if also supplying an event).

2

string

optional, default value=nil

Event to test.

Returns:

  1. nil

Example:

Trigger advice when a player unit rallies.
advice_player_unit_rallies:add_trigger_condition(
    true,
    "ScriptEventPlayerUnitRallies"
);

Example:

Trigger advice when one of the player's giants becomes visible to the enemy.
advice_player_giant:add_trigger_condition(
    function()
        local enemy_alliance = advice_player_giant.enemy_alliance;
        local player_giants = advice_player_giant.player_giants;
        local num_visible_player_giants = num_units_passing_test(
            player_giants,
            function(unit)
                return unit:is_visible_to_alliance(enemy_alliance);
            end
        );
        return num_visible_player_giants > 0;
    end
);

defined in ../working_data/script/_lib/lib_battle_advice.lua, line 809

Back to top

Halt Conditions

Halt conditions tell advice monitors when to stop monitoring. For example, advice about preparing an ambush would be inappropriate for playback when the two armies engage, so such an advice monitor could be halted. Like start and trigger conditions, halt conditions can be supplied as events, conditions, or events and conditions.

advice_monitor:add_halt_condition(function condition, [string event])
Adds a halt condition for the advice monitor. Supply one of the following combination of arguments:
  • A condition function that returns a boolean value. In this case, the condition will be polled until it passes, at which point the monitor halts.

  • A condition function that returns a boolean value, and an event. In this case, the event will be listened for and, when received, the condition checked. Should it pass, the advice monitor will halt.

  • true in place of a condition function, and an event. In this case, the advice monitor will halt when the event is received.

    • Parameters:

    1

    function

    Conditional function. Supply a function that returns a boolean value, or true (if also supplying an event).

    2

    string

    optional, default value=nil

    Event to test.

    Returns:

    1. nil

    Example:

    Halt when the "enemy victory point captured" aide-de-camp message is shown.
    advice_player_captures_victory_point:add_trigger_condition(
        function(context)
            return context.string == "adc_enemy_point_captured"
        end,
        "BattleAideDeCampEvent"
    );

    Example:

    Halt when the ScriptEventPlayerApproachingVictoryPoint event is received.
    advice_player_approaches_victory_point:add_trigger_condition(
        true,
        "ScriptEventPlayerApproachingVictoryPoint"
    );

    defined in ../working_data/script/_lib/lib_battle_advice.lua, line 871

    advice_monitor:add_halt_on_advice_monitor_triggering(string name)
    Halts this advice monitor when another advice monitor successfully triggers its advice. The other advice monitor is specified by its name.

    Parameters:

    1

    string

    Name of advice monitor to halt on.

    Returns:

    1. nil

    defined in ../working_data/script/_lib/lib_battle_advice.lua, line 911

    advice_monitor:add_halt_advice_monitor_on_trigger(string name)
    Halts another advice monitor when this monitor successfully triggers. The other advice monitor is specified by its name.

    Parameters:

    1

    string

    Name of advice monitor to halt when this monitor triggers.

    Returns:

    1. nil

    defined in ../working_data/script/_lib/lib_battle_advice.lua, line 924

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