[Modding] RTW: How-to: Add a background script to your mod

[jimkatalanos]

Author: HouseOfHam
Original Thread: How-to: Add a background script to your mod

How-to: Add a background script to your mod

First, a bit of terminology:

campaign script - A script called at the end of the descr_strat.txt file. This script only runs once, when a new campaign is first started. Saving/loading the game is disabled while this type of script runs, so it's a good idea to keep this type of script short, only using it for basic initialization and to kick off a background script. This is the type of script used for the Sons of Mars tutorial campaign in vanilla RTW.

background script - This type of script is started via an advice thread and, just like the name suggests, runs in the background. The 2 biggest advantages offered by background scripts are: 1) Being able to save/load the game while the script is running, and 2) Being able to restart the script after loading a saved game. This type of script is often also referred to as 'show me' scripts, due to the old method of starting such script, which required clicking the advisor 'Show me how' button. This type of script is used to add features like 4-turns-per-year and opens the way to a multitude of other possibilities, including scripted missions, spawning armies, and much more. A background script keeps running until you exit the game.

on-demand script - This type of script is used to run a small, self-contained piece of code. Once the code has been run, the script terminates. For example, some mods include a script that you can run before making a diplomatic offer that will force the AI to accept it. This type of script is usually triggered by pressing one of the less-frequently used buttons in the UI. For example, the '?' button in the Help scroll.

Adding a background script

This will guide you through all the steps of adding a background script.

You must complete at least the instructions in sections I & III before it will work. Section II is optional, but is usually good to include to reduce the amount of clicking the player has to do. Section IV is just additional information to help you get started with scripting.

Section I: Setting up an advice thread

1. Add a new thread to export_descr_advice.txt:

;------------------------------------------
AdviceThread My_Script_Thread
    GameArea Campaign

    Item my_script_Item_1
        Uninhibitable
        Verbosity  0 
        Threshold  1 
        MaxRepeats  0 
        RepeatInterval  1 
        Attitude Normal
        Presentation Default
        Title my_script_Title_1
        On_display scripts\show_me\my_script.txt
        Text my_script_Text_1

The On_display line creates an association between this advice thread and a script specified on it. The script will run automatically as soon as the adviser text box opens. If adviser is set to voice-only, the script will run automatically when the advice thread is triggered/advanced.

2. At the end of the export_descr_advice.txt file, add the following triggers for the above advice thread.

;------------------------------------------
Trigger my_script_trigger_1
    WhenToTest ButtonPressed

    Condition I_ThreadCount My_Script_Thread = 0
    
    AdviceThread My_Script_Thread  1

;------------------------------------------
Trigger my_script_trigger_2
    WhenToTest CharacterSelected

    Condition I_ThreadCount My_Script_Thread = 0
    
     AdviceThread My_Script_Thread  1

;------------------------------------------
Trigger my_script_trigger_3
    WhenToTest SettlementSelected

    AdviceThread My_Script_Thread  1

These triggers will be used to restart the script after loading a saved game. When you load a saved game, the first time any of these are triggered, the advisor portrait will come up. Click on it once to restart the script.

3. Add the following lines at the end of the text\export_advice.txt file:

{my_script_Title_1}Background Script
{my_script_Text_1}Script started.

Section II: Running the background script automatically when a new campaign starts

1. Add the following at the very end of descr_strat.txt:

script
campaign_script.txt

This uses a campaign script to fire off the background script.

2. In the same folder with the descr_strat.txt file for your mod, create a new file called campaign_script.txt (our campaign script) and put these lines into it:

script

wait 1
console_command clear_messages
wait 1
advance_advice_thread My_Script_Thread
wait 1
select_ui_element advisor_portrait_button
simulate_mouse_click lclick_up

end_script

Section III: Creating the script - What every script should have

1. In the scripts\show_me folder, create a new file called my_script.txt <-- This is the file referenced by the On_display line in the advice thread in Section I. Traditionally, everyone puts their scripts into scripts\show_me, but you can put it anywhere you like and call it anything you want, as long as you update the On_display line to point to it.

2. What to put into the script file:

script

; Anything following a semicolon is a comment.

; Remove the adviser portrait from screen.
select_ui_element advisor_dismiss_button
simulate_mouse_click lclick_up

; Wait for it to go away.
while I_AdvisorVisible
end_while

suspend_unscripted_advice true

; Open the adviser message bubble automatically whenever advance_advice_thread is called.
; I recommend using this method instead of the select_ui_element + simulate_mouse_click approach.
; Do NOT mix both methods, though, or the advisor will show and then immediately close before
; you get a chance to read the text.
declare_show_me

; Very useful for debugging - uncomment to use
;console_command toggle_perfect_spy

; Handle saved game reloads
monitor_event GameReloaded TrueCondition
  terminate_script
end_monitor

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; This is where to put your own code
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; For example, this will give you 1 gold at the beginning of every turn
monitor_event FactionTurnStart FactionIsLocal
  console_command add_money 1
end_monitor

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; End of your code
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Spin forever - Do not let the script terminate or any monitors you have set up will immediately get thrown away.
while I_TurnNumber < 99999
  suspend_unscripted_advice true
end_while

end_script

Section IV: Learning Scripting - Where to go from here

1. Other resources

Recommended reading:

• Beginning Guide to Scripting
• Intermediate Guide to Scripting
• Check out other tutorials in the parent forum

Referrence materials:

• Unofficial scripting documentation (updated for BI) - Released by Jerome Grasdyke (lead developer at Creative Arts) back in Sep'05
• Available UI elements that can be accessed via scripting

Where to ask for advice:

• TWC Text editing and Scripting forum
• Modding Questions forum at .org

2. A few notes to help you with your scripting:

- The following commands do not work inside a monitor_event block: wait, campaign_wait, battle_wait, while, and nested monitor_event/monitor_conditions blocks. If you try to use them, your script will freeze.

- Most scripting commands and conditions use objects exported by events as an implied parameter and thus only work in the context of a monitor_event block. The type of object expected by the command/condition must match the type of one of the objects exported by the monitored event, or they won't work.

- The exception to the above rule are commands that start with "I_" and console commands, because parameters for these commands are explicitly named objects (i.e. specific characters/settlements/etc.), or they do not require parameters.

- Always, always, always have -show_err in your shortcut's target line!!!

- Errors in console_command lines never produce any error messages and never cause CTDs. They're just quietly ignored.

- Other errors, depending on how severe they are, can cause a CTD or a pop-up dialog box with an error message when shutting down the game.

- Some commands can freeze the game completely, so it won't respond at all, even to Alt-F4. I found that out when I tried to add the following code (don't try this at home!):

monitor_event CharacterSelected CharacterIsLocal
    call_object_shortcut hud_select_prev_item_cycle
end_monitor

So, don't do it!

- Clicking on an army that's inside a settlement does not generate a CharacterSelected event

- It's only possible to use scripting to move field armies/characters. AFAIK, it does not work on armies/characters that are inside a settlement.

- To be able to take full advantage of all the possibilities scripting offers, you should become familiar with a few other areas of modding. In particular, having a good understanding of these will make you a much more effective scripter: descr_strat.txt, advice threads, traits & ancillaries, and buildings.

- Unlike MTW2, counter values are NOT saved when a game is saved. This means that you'll have to use other means to keep track of important information that you'll need when the script is restarted. The most common ways are using traits (especially hidden traits), ancillaries, and/or buildings.

- Advice thread counter is incremented when you click on the advisor portrait to open the text bubble.

- The AbandonShowMe event is generated when you dismiss the advisor.

ps: Feel free to discuss here or at .org (http://forums.totalwar.org/vb/showthread.php?t=104133)