How-to: Block user controls while advice is displayed

[HouseOfHam]

This is somewhat of a useful thing to do for important advisor messages that you don't want the player to miss. Hopefully, it'll make them read the message before closing it. The idea behind this was borrowed from CA's historical battle scripts.

    declare_timer advisorTimer

    ; disable all controls
    disable_cursor
    disable_shortcuts true
    inhibit_camera_input true
    disable_shortcuts advisor_portrait_button false
    filter_all_ui_commands off

    ; turn cursor and main menu back on
    enable_cursor
    disable_entire_ui
    disable_shortcuts options_button false

   ; turn advisor controls back on
    disable_shortcuts advisor_dismiss_button false
    disable_shortcuts dismiss_advice false
    disable_shortcuts advisor_portrait_button false

    dismiss_advice                  ; dismiss any previously shown advice

    advance_advice_thread ImportantMessageThread 1
    ; if your script doesn't have declare_show_me at the top, uncomment these 2 lines
    ;select_ui_element advisor_portrait_button
    ;simulate_mouse_click lclick_up

    restart_timer advisorTimer

    ; Dismiss to continue. If not dismissed after 10 seconds, show hint.
    while I_AdvisorVisible
        monitor_conditions I_TimerElapsed advisorTimer > 10000
            ui_flash_start advisor_dismiss_button    ; uses ui_indicator slot 2
            terminate_monitor
        end_monitor
    end_while

    ui_flash_stop

    ; turn all controls back on
    filter_all_ui_commands on
    enable_entire_ui
    disable_shortcuts false        
    inhibit_camera_input false

Warning: This code will not work inside a monitor_event block.
Explanation: This code uses a while loop to determine when to re-enable user controls. Unfortunately, while loops and wait commands cannot be used inside monitor_event blocks and will freeze your script if used. Taking the while loop out does not solve the problem, as it makes the desired effect disappear (it would be like switching the lights off and right back on). This limits the usability of this code to script's initialization section, 4tpy script, historical battle scripts, and similar places where processing is fairly linear, and monitor_conditions blocks.